Internet Engineering Task Force (IETF) J. Lentini 


Request for Comments: 7532 NetApp 
Category: Standards Track R. Tewari 
ISSN: 2070-1721 IBM Almaden 


C. Lever, Ed. 
Oracle Corporation 
March 2015 


Namespace Database (NSDB) Protocol for Federated File Systems 
Abstract 
This document describes a file system federation protocol that 
enables file access and namespace traversal across collections of 
independently administered fileservers. The protocol specifies a set 
of interfaces by which fileservers with different administrators can 
form a fileserver federation that provides a namespace composed of 
the file systems physically hosted on and exported by the constituent 
fileservers. 
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1. Introduction 


A federated file system enables file access and namespace traversal 
in a uniform, secure, and consistent manner across multiple 
independent fileservers within an enterprise or across multiple 
enterprises. 


This document specifies a set of protocols that allow fileservers, 
possibly from different vendors and with different administrators, to 
cooperatively form a federation containing one or more federated file 
Systems. Each federated file system's namespace is composed of the 
file systems physically hosted on and exported by the federation's 
fileservers. A federation comprises a common namespace across all 
its fileservers. A federation can project multiple namespaces and 
enable clients to traverse each one. A federation can contain an 
arbitrary number of namespace repositories, each belonging to a 
different administrative entity and each rendering a part of the 
namespace. A federation might also have an arbitrary number of 
administrative entities responsible for administering disjoint 
subsets of the fileservers. 


Traditionally, building a namespace that spans multiple fileservers 
has been difficult for two reasons. First, the fileservers that 
export pieces of the namespace are often not in the same 
administrative domain. Second, there is no standard mechanism for 
the fileservers to cooperatively present the namespace.  Fileservers 
may provide proprietary management tools, and in some cases, an 
administrator may be able to use the proprietary tools to build a 
shared namespace out of the exported file systems. However, relying 
on vendor-specific proprietary tools does not work in larger 
enterprises or when collaborating across enterprises because the 
fileservers are likely to be from multiple vendors or use different 
Software versions, each with their own namespace protocols, with no 
common mechanism to manage the namespace or exchange namespace 
information. 
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The federated file system protocols in this document define how to 
construct a namespace accessible by a Network File System (NFS) 
version 4.0 [RFC7530], NFSv4.1 [RFC5661], or newer client and have 
been designed to accommodate other file-access protocols in the 
future. 


The requirements for federated file systems are described in 
[RFC5716]. A protocol for administering a fileserver's namespace is 
described in [RFC7533]. The mechanism for discovering the root of a 
federated namespace is described in [RFC6641]. 


In the rest of the document, the term "fileserver" denotes a 
fileserver that is part of a federation. 


1.1. Requirements Language 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 
document are to be interpreted as described in [RFC2119]. 


2. Overview of Features and Concepts 
2.1. File-Access Protocol 


A file-access protocol is a network protocol for accessing data. The 
NFSv4.0 protocol [RFC7530] is an example of a file-access protocol. 


2.2. File-Access Client 


File-access clients are standard, off-the-shelf network-attached 
storage (NAS) clients that communicate with fileservers using a 
standard file-access protocol. 


2.3. Fileserver 


Fileservers are servers that store physical fileset data or refer 
file-access clients to other fileservers. A fileserver provides 
access to its shared file system data via a file-access protocol. A 
fileserver may be implemented in a number of different ways, 
including a single system, a cluster of systems, or some other 
configuration. 


2.4. Referral 
A referral is a mechanism by which a fileserver redirects a file- 
access client to a different fileserver or export. The exact 


information contained in a referral varies from one file-access 
protocol to another. The NFSv4.0 protocol, for example, defines the 
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fs locations attribute for returning referral information to NFSv4.0 


clients. The NFSv4.1 protocol introduces the fs locations info 
attribute that can return richer referral information to its clients. 
NFSv4.1 fileservers may use either attribute during a referral. Both 


attributes are defined in [RFC5661]. 
2.5. Namespace 


The goal of a unified namespace is to make all managed data available 
to any file-access client via the same path in a common file system 
namespace. This should be achieved with minimal or zero 
configuration on file-access clients. In particular, updates to the 
common namespace should not require configuration changes to any 
file-access client. 


Filesets, which are the units of data management, are a set of files 
and directories. From the perspective of file-access clients, the 
common namespace is constructed by mounting filesets that are 
physically located on different fileservers. The namespace, which is 
defined in terms of fileset names and locations, is stored in a set 
of namespace repositories, each managed by an administrative entity. 


The namespace schema defines the model used for populating, 
modifying, and querying the namespace repositories. It is not 
required by the federation that the namespace be common across all 
fileservers. It should be possible to have several independently 
rooted namespaces. 


2.6. Fileset 


A fileset is loosely defined as a set of files and the directory tree 
that contains them. The fileset abstraction is the basic unit of 
data management. Depending on the configuration, a fileset may be 
anything from an individual directory of an exported file system to 
an entire exported file system on a fileserver. 


2.7. Fileset Name (FSN) 
A fileset is uniquely represented by its fileset name (FSN). An FSN 
is considered unique across a federation. After an FSN is created, 


it is associated with one or more fileset locations (FSLs) on one or 
more fileservers. 
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An FSN consists of: 


NsdbName: the network location of the Namespace Database (NSDB) 
node that contains authoritative information for this FSN. 


FsnUuid: a UUID (universally unique identifier), conforming to 
[RFC4122], that is used to uniquely identify an FSN. 


FsnTTL: the time-to-live of the FSN's FSL information, in 
seconds. Fileservers MUST NOT use cached FSL records after the 
parent FSN's FsnTTL has expired. An FsnTTL value of zero 
indicates that fileservers MUST NOT cache the results of 
resolving this FSN. 


The NsdbName is not physically stored as an attribute of the record. 
The NsdbName is obvious to any client that accesses an NSDB and is 
indeed authenticated in cases where Transport Layer Security (TLS) is 
in effect. 


The FsnUuid and NsdbName values never change during an FSN's 
lifetime. However, an FSN's FSL information can change over time and 
is typically cached on fileservers for performance. More detail on 
FSL caching is provided in Section 2.8.3. 


An FSN record may also contain: 


Annotations:  name/value pairs that can be interpreted by a 
fileserver. The semantics of this field are not defined by 
this document. These tuples are intended to be used by higher- 
level protocols. 


Descriptions: text descriptions. The semantics of this field are 
not defined by this document. 


2.8. Fileset Location (FSL) 


An FSL describes one physical location where a complete copy of the 
fileset's data resides. An FSL contains generic and type-specific 
information that together describe how to access the fileset data at 
this location. An FSL's attributes can be used by a fileserver to 
decide which locations it will return to a file-access client. 
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An FSL consists of: 


FslUuid: a UUID, conforming to [RFC4122], that is used to 
uniquely identify an FSL. 


FsnUuid: the UUID of the FSL's FSN. 


NsdbName: the network location of the NSDB node that contains 
authoritative information for this FSL. 


The NsdbName is not stored as an attribute of an FSL record for the 
same reason it is not stored in FSN records. 


An FSL record may also contain: 


Annotations:  name/value pairs that can be interpreted by a 
fileserver. The semantics of this field are not defined by 
this document. These tuples are intended to be used by higher- 
level protocols. 


Descriptions: text descriptions. The semantics of this field are 
not defined by this document. 


In addition to the attributes defined above, an FSL record contains 
attributes that allow a fileserver to construct referrals. For each 
file-access protocol, a corresponding FSL record subtype is defined. 


This document defines an FSL subtype for NFS. An NFS FSL contains 
information suitable for use in one of the NFSv4 referral attributes 
(e.g., fs locations or fs locations info, described in [RFC5661]). 
Section 4.2.2.4 describes the contents of an NFS FSL record. 


A fileset may also be accessible by file-access protocols other than 
NFS. The contents and format of such FSL subtypes are not defined in 
this document. 


2.8.1. The NFS URI Scheme 


To capture the location of an NFSv4 fileset, we extend the NFS URL 


scheme specified in [RFC2224]. This extension follows rules for 
defining Uniform Resource Identifier schemes (see [RFC3986]). In the 
following text, we refer to this extended NFS URL scheme as an NFS 
URI. 


An NFS URI MUST contain both an authority and a path component. It 
MUST NOT contain a query component or a fragment component. Use of 
the familiar "nfs" scheme name is retained. 


Lentini, et al. Standards Track [Page 8] 


REC 7532 NSDB Protocol for Federated File Systems March 2015 


2.8.1.1. The NFS URI Authority Component 


The rules for encoding the authority component of a generic URI are 
Specified in section 3.2 of [RFC3986]. The authority component of an 
NFS URI MUST contain the host subcomponent. For globally scoped NFS 
URIs, a hostname used in such URIs SHOULD be a fully qualified domain 
name. See section 3.2.2 of [RFC3986] for rules on encoding non-ASCII 
characters in hostnames. 


An NFS URI MAY contain a port subcomponent as described in section 
3.2.3 of [RFC3986]. If this subcomponent is missing, a port value of 
2049 is assumed, as specified in [RFC7530], Section 3.1. 


2.8.1.2. The NFS URI Path Component 


The rules for encoding the path component of a generic URI are 
Specified in Section 3.3 of [RFC3986]. 


According to Sections 5 and 6 of [RFC2224], NFS URLs specify a 
pathname relative to an NFS fileserver's public filehandle. However, 
NFSv4 fileservers do not expose a public filehandle. Instead, NFSv4 
pathnames contained in an NFS URI are evaluated relative to the 
pseudoroot of the fileserver identified in the URI's authority 
component. 


Each component of an NFSv4 pathname is represented as a component4 
string (see Section 3.2, "Basic Data Types", of [RFC5661]). The 
component4 elements of an NFSv4 pathname are encoded as path segments 
in an NFS URI. NFSv4 pathnames MUST be expressed in an NFS URI as an 
absolute path. An NFS URI path component MUST NOT be empty. The NFS 
URI path component starts with a slash ("/") character, followed by 
one or more path segments that each start with a slash ("/") 
character [RFC3986]. 


Therefore, a double slash always follows the authority component of 
an NFS URI. For example, the NFSv4 pathname "/" is represented by 
two slash ("/") characters following an NFS URI's authority 
component. 


The component names of an NFSv4 pathname MUST be prepared using the 
component name rules defined in Section 12 ("Internationalization") 
of [RFC7530] prior to encoding the path component of an NFS URI. As 
Specified in [RFC3986], any non-ASCII characters and any URI-reserved 
characters, such as the slash ("/") character, contained in a 
component4 element MUST be represented by URI percent encoding. 
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2.8.1.3. Encoding an NFS Location in an FSL 


25s 


8 


The path component of an NFS URI encodes the rootpath field of the 
NFSv4 fs location4 data type or the "fli rootpath" of the NFSv4 
fs locations item4 data type (see [RFC5661]). 


In its server field, the NFSv4 fs location4 data type contains a list 
of universal addresses and DNS labels. Each may optionally include a 
port number. The exact encoding requirements for this information is 
found in Section 12.6 of [RFC7530]. The NFSv4 fs locations item4 
data type encodes the same data in its fli entries field (see 
[RFC5661]). This information is encoded in the authority component 
of an NFS URI. 


The server and fli entries fields can encode multiple server 
hostnames that share the same pathname. An NFS URI, and hence an FSL 
record, represents only a single hostname and pathname pair. An NFS 
fileserver MUST NOT combine a set of FSL records into a single 

fs location4 or fs locations item4 unless each FSL record in the set 
contains the same rootpath value and extended file system 
information. 


.2. Mutual Consistency across Fileset Locations 


All of the FSLs that have the same FSN (and thereby reference the 
same fileset) are equivalent from the point of view of access by a 
file-access client. Different fileset locations for an FSN represent 
the same data, though potentially at different points in time. 
Fileset locations are equivalent but not identical. Locations may be 
either read-only or read-write. Typically, multiple read-write 
locations are backed by a clustered file system while read-only 
locations are replicas created by a federation-initiated or external 
replication operation.  Read-only locations may represent consistent 
point-in-time copies of a read-write location. The federation 
protocols, however, cannot prevent subsequent changes to a read-only 
location nor guarantee point-in-time consistency of a read-only 
location if the read-write location is changing. 


Regardless of the type, one file-access client may be referred to a 
location described by one FSL while another client chooses to use a 
location described by another FSL. Since updates to each fileset 
location are not controlled by the federation protocol, it is the 
responsibility of administrators to guarantee the functional 
equivalence of the data. 


The federation protocols do not guarantee that different fileset 
locations are mutually consistent in terms of the currency of their 
data. However, they provide a means to publish currency information 
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so that all fileservers in a federation can convey the same 
information to file-access clients during referrals. Clients use 
this information to ensure they do not revert to an out-of-date 
version of a fileset's data when switching between fileset locations. 
NFSv4.1 provides guidance on how replication can be handled in such a 
manner. In particular, see Section 11.7 of [RFC5661]. 


2.8.3. Caching of Fileset Locations 


To resolve an FSN to a set of FSL records, a fileserver queries the 
NSDB node named in the FSN for FSL records associated with this FSN. 
The parent FSN's FsnTTL attribute (see Section 2.7) specifies the 
period of time during which a fileserver may cache these FSL records. 


The combination of FSL caching and FSL migration presents a 
challenge. For example, suppose there are three fileservers named A, 
B, and C. Suppose further that fileserver A contains a junction J to 
fileset X stored on fileserver B (see Section 2.10 for a description 
of junctions). 


Now suppose that fileset X is migrated from fileserver B to 
fileserver C, and the corresponding FSL information for fileset X in 
the authoritative NSDB is updated. 


If fileserver A has cached FSLs for fileset X, a file-access client 
traversing junction J on fileserver A will be referred to fileserver 
B, even though fileset X has migrated to fileserver C. If fileserver 
A had not cached the FSL records, it would have queried the NSDB and 
obtained the correct location of fileset X. 


Typically, the process of fileset migration leaves a redirection on 
the source fileserver in place of a migrated fileset (without such a 
redirection, file-access clients would find an empty space where the 
migrated fileset was, which defeats the purpose of a managed 
migration). 


This redirection might be a new junction that targets the same FSN as 
other junctions referring to the migrated fileset, or it might be 
some other kind of directive, depending on the fileserver 
implementation, that simply refers file-access clients to the new 
location of the migrated fileset. 
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Back to our example. Suppose, as part of the migration process, a 
junction replaces fileset X on fileserver B. Later, either: 


o New file-access clients are referred to fileserver B by stale FSL 
information cached on fileserver A, or 


o File-access clients continue to access fileserver B because they 
cache stale location data for fileset X. 


In either case, thanks to the redirection, file-access clients are 
informed by fileserver B that fileset X has moved to fileserver C. 


Such redirecting junctions (here, on fileserver B) would not be 
required to be in place forever. They need to stay in place at least 
until FSL entries cached on fileservers and locations cached on file- 
access clients for the target fileset are invalidated. 


The FsnTTL field in the FSL's parent FSN (see Section 2.7) specifies 
an upper bound for the lifetime of cached FSL information and thus 
can act as a lower bound for the lifetime of redirecting junctions. 


For example, suppose the FsnTTL field contains the value 3600 seconds 
(one hour). In such a case, administrators SHOULD keep the 
redirection in place for at least one hour after a fileset migration 
has taken place because a referring fileserver might cache the FSL 
data during that time before refreshing it. 


To get file-access clients to access the destination fileserver more 
quickly, administrators SHOULD set the FsnTTL field of the migrated 
fileset to a low number or zero before migration begins. It can be 
reset to a more reasonable number at a later point. 


Note that some file-access protocols do not communicate location 
cache expiry information to file-access clients. In some cases, it 
may be difficult to determine an appropriate lifetime for redirecting 
junctions because file-access clients may cache location information 
indefinitely. 


2.8.4. Generating a Referral from Fileset Locations 


After resolving an FSN to a set of FSL records, the fileserver 
generates a referral to redirect a file-access client to one or more 
of the FSN's FSLs. The fileserver converts the FSL records to a 
referral format understood by a particular file-access client, such 
as an NFSv4 fs locations or fs locations info attribute. 


Lentini, et al. Standards Track [Page 12] 


REC 7532 NSDB Protocol for Federated File Systems March 2015 


To give file-access clients as many options as possible, the 
fileserver SHOULD include the maximum possible number of FSL records 
in a referral. However, the fileserver MAY omit some of the FSL 
records from the referral. For example, the fileserver might omit an 
FSL record because of limitations in the file-access protocol's 
referral format. 


For a given FSL record, the fileserver MAY convert or reduce the FSL 
record's contents in a manner appropriate to the referral format. 
For example, an NFS FSL record contains all the data necessary to 
construct an fs locations info attribute, but an fs locations info 
attribute contains several pieces of information that are not found 
in the simpler fs locations attribute. A fileserver constructs 
entries in an fs locations attribute using the relevant contents of 
an NFS FSL record. 


Whenever the fileserver converts or reduces FSL data, the fileserver 
SHOULD attempt to maintain the original meaning where possible. For 
example, an NFS FSL record contains the rank and order information 
that is included in an fs locations info attribute (see NFSv4.1's 
FSLI4BX_READRANK, FSLI4BX_READORDER, FSLIA4BX WRITERANK, and 
FSLI4BX_WRITEORDER). While this rank and order information is not 
explicitly expressible in an fs_locations attribute, the fileserver 
can arrange the fs locations attribute's locations list based on the 
rank and order values. 


Another example: A single NFS FSL record contains the hostname of one 
fileserver. A single fs locations attribute can contain a list of 
fileserver names. An NFS fileserver MAY combine two or more FSL 
records into a single entry in an fs locations or fs locations info 
array only if each FSL record contains the same pathname and extended 
file system information. 


Refer to Sections 11.9 and 11.10 of the NFSv4.1 protocol 
Specification [RFC5661] for further details. 


2.9. Namespace Database (NSDB) 
The NSDB service is a federation-wide service that provides 
interfaces to define, update, and query FSN information, FSL 


information, and FSN-to-FSL mapping information. 


An individual repository of namespace information is called an NSDB 


node. The difference between the NSDB service and an NSDB node is 
analogous to that between the DNS service and a particular DNS 
server. 
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Each NSDB node is managed by a single administrative entity. A 
single administrative entity can manage multiple NSDB nodes. 


Each NSDB node stores the definition of the FSNs for which it is 
authoritative. It also stores the definitions of the FSLs associated 
with those FSNs. An NSDB node is authoritative for the filesets that 
it defines. 


An NSDB MAY be replicated throughout the federation. If an NSDB is 
replicated, the NSDB MUST exhibit loose, converging consistency as 
defined in [RFC3254]. The mechanism by which this is achieved is 
outside the scope of this document. Many Lightweight Directory 
Access Protocol (LDAP) implementations support replication. These 
features MAY be used to replicate the NSDB. 


2.9.1. NSDB Client 


Each NSDB node supports an LDAP [RFC4510] interface. An NSDB client 
is software that uses the LDAP protocol to access or update namespace 
information stored on an NSDB node. 


A domain's administrative entity uses NSDB client software to manage 
information stored on NSDB nodes. Details of these transactions are 
discussed in Section 5.1. 


Fileservers act as an NSDB client when contacting a particular NSDB 
node to resolve an FSN to a set of FSL records. The resulting 
location information is then transferred to file-access clients via 
referrals. Therefore, file-access clients never need to access NSDBs 
directly. These transactions are described in Section 5.2. 


2.10. Junctions and Referrals 


A junction is a point in a particular fileset namespace where a 
Specific target fileset may be attached. If a file-access client 
traverses the path leading from the root of a federated namespace to 
the junction referring to a target fileset, it should be able to 
mount and access the data in that target fileset (assuming 
appropriate permissions). In other words, a junction can be viewed 
as a reference from a directory in one fileset to the root of the 
target fileset. 


A junction can be implemented as a special marker on a directory or 
by some other mechanism in the fileserver's underlying file system. 
What data is used by the fileserver to represent junctions is not 


defined by this document. The essential property is that given a 
junction, a fileserver must be able to find the FSN for the target 
fileset. 
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When a file-access client reaches a junction, the fileserver refers 
the client to a list of FSLs associated with the FSN targeted by the 
junction. The client can then mount one of the associated FSLs. 


The federation protocols do not limit where and how many times a 
fileset is mounted in the namespace. Filesets can be nested; a 
fileset can be mounted under another fileset. 


2.11. Unified Namespace and the Root Fileset 


The root fileset, when defined, is the top-level fileset of the 
federation-wide namespace. The root of the unified namespace is the 
top level directory of this fileset. A set of designated fileservers 
in the federation can export the root fileset to render the 
federation-wide unified namespace. When a file-access client mounts 
the root fileset from any of these designated fileservers, it can 
view a common federation-wide namespace. 


2.12. UUID Considerations 


To ensure FSN and FSL records are unique across a domain, Federated 
File System (FedFS) employs UUIDs conforming to [RFC4122] to form the 
distinguished names of LDAP records containing FedFS data (see 
Section 4.2.2.2). 


Because junctions store a tuple containing an FSN UUID and the name 
and port of an NSDB node, an FSN UUID must be unique only on a single 
NSDB node. An FSN UUID collision can be detected immediately when an 
administrator attempts to publish an FSN or FSL by storing it under a 
Specific NSDB Container Entry (NCE) on an authoritative NSDB host. 


Note that one NSDB node may store multiple NCEs, each under a 
different namingContext. If an NSDB node must contain more than one 
NCE, the federation's admin entity SHOULD provide a robust method for 
preventing FSN UUID collisions between FSNs that reside on the same 
NSDB node but under different NCEs. 


Because FSLs are children of FSNs, FSL UUIDs must be unique for just 
a single FSN. As with FSNs, as soon as an FSL is published, its 
uniqueness is guaranteed. 


A fileserver performs the operations described in Section 5.2 as an 
unauthenticated user. Thus, distinguished names of FSN and FSL 
records, as well as the FSN and FSL records themselves, are required 
to be readable by anyone who can bind anonymously to an NSDB node. 
Therefore, FSN and FSL UUIDs should be considered public information. 
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Version 1 UUIDs contain a host's Media Access Control (MAC) address 
and a timestamp in the clear. This gives provenance to each UUID, 
but attackers can use such details to guess information about the 
host where the UUID was generated.  Security-sensitive installations 
should be aware that on externally facing NSDBs, UUIDs can reveal 
information about the hosts where they are generated. 


In addition, version 1 UUIDs depend on the notion that a hardware MAC 
address is unique across machines. As virtual machines do not depend 
on unique physical MAC addresses and, in any event, an administrator 
can modify the physical MAC address, version 1 UUIDs are no longer 
considered sufficient. 


To minimize the probability of UUIDs colliding, a consistent 
procedure for generating UUIDs should be used throughout a 
federation. Within a federation, UUIDs SHOULD be generated using the 
procedure described for version 4 of the UUID variant specified in 
[RFC4122]. 


3. Examples 


In this section we provide examples and discussion of the basic 
operations facilitated by the federated file system protocol: 
creating a fileset, adding a replica of a fileset, resolving a 
junction, and creating a junction. 


3.1. Creating a Fileset and Its FSL(s) 


A fileset is the abstraction of a set of files and the directory tree 
that contains them. The fileset abstraction is the fundamental unit 
of data management in the federation. This abstraction is 
implemented by an actual directory tree whose root location is 
Specified by a fileset location (FSL). 


In this section, we describe the basic requirements for starting with 
a directory tree and creating a fileset that can be used in the 
federation protocols. Note that we do not assume that the process of 
creating a fileset requires any transformation of the files or the 
directory hierarchy. The only thing that is required by this process 
is assigning the fileset a fileset name (FSN) and expressing the 
location of the implementation of the fileset as an FSL. 


There are many possible variations to this procedure, depending on 
how the FSN that binds the FSL is created and whether other replicas 
of the fileset exist, are known to the federation, and need to be 
bound to the same FSN. 
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It is easiest to describe this in terms of how to create the initial 
implementation of the fileset and then describe how to add replicas. 


3.1.1. Creating a Fileset and an FSN 


The following administrative steps create an FSN, which is used to 
track all replicas of a single physical dataset. 


1. Choose the NSDB node that will keep track of the FSL(s) and 
related information for the fileset. 


2. Create an FSN in the NSDB node. 


The FSN UUID is chosen by the administrator or generated 
automatically by administration software. The former case is 
used if the fileset is being restored, perhaps as part of 
disaster recovery, and the administrator wishes to specify the 
FSN UUID in order to permit existing junctions that reference 
that FSN to work again. 


At this point, the FSN exists, but its fileset locations are 
unspecified. 


3. For the FSN created above, create an FSL in the NSDB node that 
describes the physical location of the fileset data. 


3.1.2. Adding a Replica of a Fileset 


Adding a replica is straightforward: the NSDB node and the FSN are 
already known. The only remaining step is to add another FSL. 


Note that the federation protocols provide only the mechanisms to 
register and unregister replicas of a fileset.  Fileserver-to- 
fileserver replication protocols are not defined. 


3.2. Junction Resolution 
A fileset may contain references to other filesets. These references 
are represented by junctions. If a file-access client requests 


access to a fileset object that is a junction, the fileserver 
resolves the junction to discover one or more FSLs that implement the 
referenced fileset. 


There are many possible variations to this procedure, depending on 
how the junctions are represented by the fileserver and how the 
fileserver performs junction resolution. 
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Step 4 is the only step that interacts directly with the federation 


protocols. The rest of the steps may use platform-specific 

interfaces. 

1. The fileserver determines that the object being accessed is a 
junction. 


2. The fileserver does a local lookup to find the FSN of the target 
fileset. 


3. Using the FSN, the fileserver finds the NSDB node responsible for 
the target FSN. 


4. The fileserver contacts that NSDB node and asks for the set of 
FSLs that implement the target FSN. The NSDB node responds with 
a (possibly empty) set of FSLs. 


5. The fileserver converts one or more of the FSLs to the location 
type used by the file-access client (e.g., an NFSv4 fs locations 
attribute as described in [RFC5661]). 


6. The fileserver redirects (in whatever manner is appropriate for 
the client) the client to the location(s). 


3.3. Example Use Cases for Fileset Annotations 


Fileset annotations can convey additional attributes of a fileset. 
For example, fileset annotations can be used to define relationships 
between filesets that can be used by an auxiliary replication 
protocol. Consider the scenario where a fileset is created and 
mounted at some point in the namespace. A snapshot of the read-write 
FSL of that fileset is taken periodically at different frequencies 
(say, a daily or weekly snapshot). The different snapshots are 
mounted at different locations in the namespace. 


The daily snapshots are considered as different filesets from the 
weekly ones, but both are related to the source fileset. We can 
define an annotation labeling the filesets as source and replica. 

The replication protocol can use this information to copy data from 
one or more FSLs of the source fileset to all the FSLs of the replica 
fileset. The replica filesets are read-only while the source fileset 
is read-write. 


This follows the traditional Andrew File System (AFS) model of 


mounting the read-only volume at a path in the namespace different 
from that of the read-write volume [AFS]. 
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The federation protocol does not control or manage the relationship 
among filesets. It merely enables annotating the filesets with user- 
defined relationships. 


Another potential use for annotations is recording references to an 
FSN. A single annotation containing the number of references could 
be defined, or multiple annotations, one per reference, could be used 
to store detailed information on the location of each reference. 


As with the replication annotation described above, the maintenance 
of reference information would not be controlled by the federation 
protocol. The information would most likely be non-authoritative 
because the ability to create a junction does not require the 
authority to update the FSN record. In any event, such annotations 
could be useful to administrators for determining if an FSN is 
referenced by a junction. 


4. NSDB Configuration and Schema 


This section describes how an NSDB is constructed using an LDAP 


Version 3 [RFC4510] directory. Section 4.1 describes the basic 
properties of the LDAP configuration that MUST be used in order to 
ensure compatibility between different implementations. Section 4.2 


defines the new LDAP attribute types and the new object types; it 
also specifies how the distinguished name (DN) of each object 
instance MUST be constructed. 


4.1. LDAP Configuration 


An NSDB is constructed using an LDAP directory. This LDAP directory 
MAY have multiple naming contexts. The LDAP directory's entry 
specific to Digital Signature Algorithm (DSA) (its rootDSE) has a 
multi-valued namingContext attribute. Each value of the 
namingContext attribute is the DN of a naming context's root entry 
(see [RFC4512]). 


For each naming context that contains federation entries (e.g., FSNs 
and FSLs): 


1. There MUST be an LDAP entry that is superior to all of the naming 
context's federation entries in the Directory Information Tree 
(DIT). This entry is termed the NSDB Container Entry (NCE). The 
NCE's children are FSNs. An FSN's children are FSLs. 


2. The naming context's root entry MUST include 
"fedfsNsdbContainerInfo" (defined in Section 4.2.2.1) as one of 
its object classes. The fedfsNsdbContainerInfo's fedfsNceDN 
attribute is used to locate the naming context's NCE. 


Lentini, et al. Standards Track [Page 19] 


REC 7532 NSDB Protocol for Federated File Systems March 2015 


If a naming context does not contain federation entries, it will not 
contain an NCE, and its root entry will not include a 
"fedfsNsdbContainerInfo" as one of its object classes. 


A fedfsNsdbContainerInfo's fedfsNceDN attribute contains the 
distinguished name (DN) of the NSDB Container Entry residing under 
this naming context. The fedfsNceDN attribute MUST NOT be empty. 


For example, an LDAP directory might have the following entries: 


-+ [root DSE] 
| namingContext: o=fedfs 
namingContext: dc-example,dc-com 
namingContext: ou-system 


| 
| 
| 
| 
*---- [o-fedfs] 
| fedfsNceDN: o=fedfs 
| 
| 
+ 


---- [dc=example, dc=com] 
fedfsNceDN: ou-fedfs,ou-corp-it,dc-example,dc-com 


t---- [ou=system] 


In this case, the "o-fedfs" namingContext has an NSDB Container Entry 
at "o=fedfs", the "dc=example,dc=com" namingContext has an NSDB 
Container Entry at "ou=fedfs,ou=corp-it,dc=example,dc=com", and the 
"ou-system" namingContext has no NSDB Container Entry. 


The NSDB SHOULD be configured with one or more privileged LDAP users. 
These users are able to modify the contents of the LDAP database. An 
administrator that performs the operations described in Section 5.1 
SHOULD authenticate using the DN of a privileged LDAP user. 


It MUST be possible for an unprivileged (unauthenticated) user to 
perform LDAP queries that access the NSDB data. A fileserver 
performs the operations described in Section 5.2 as an unprivileged 
user. 


All implementations SHOULD use the same schema. At minimum, each 
MUST use a schema that includes all objects named in the following 
sections, with all associated attributes. If it is necessary for an 
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implementation to extend the schema defined here, consider using one 
of the following ways to extend the schema: 


o Define a fedfsAnnotation key and values (see Section 4.2.1.6). 
Register the new key and values with IANA (see Section 7.1). 


o Define additional attribute types and object classes, then have 
entries inherit from a class defined in this document and from the 
implementation-defined ones. 


Given the above configuration guidelines, an NSDB SHOULD be 
constructed using a dedicated LDAP server. If LDAP directories are 
needed for other purposes, such as to store user account information, 
use of a separate LDAP server for those is RECOMMENDED. By using an 
LDAP server dedicated to storing NSDB records, there is no need to 
disturb the configuration of any other LDAP directories that store 
information unrelated to an NSDB. 


4.2. LDAP Schema 


The schema definitions provided in this document use the LDAP schema 
syntax defined in [RFC4512]. The definitions are formatted to allow 
the reader to easily extract them from the document. The reader can 
use the following shell script to extract the definitions: 


«CODE BEGINS» 


#!/bin/sh 
grep '^ *///' | sed 's?^ */// 22’ | sed 's?^ *///$??' 


«CODE ENDS» 


If the above script is stored in a file called "extract.sh", and this 
document is in a file called "spec.txt", then the reader can do: 


«CODE BEGINS» 
sh extract.sh « spec.txt » fedfs.schema 
«CODE ENDS» 


The effect of the script is to remove leading white space from each 
line, plus a sentinel sequence of "///". 
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Code components extracted from this document must include the 
following license: 


«CODE BEGINS» 


/// $ 

/// * Copyright (c) 2015 IETF Trust and the persons identified 
/// # as authors of the code. All rights reserved. 

/// # 

/// * The authors of the code are: 

/// * J. Lentini, C. Everhart, D. Ellard, R. Tewari, and M. Naik. 
/// $ 

/// * Redistribution and use in source and binary forms, with 
/// * or without modification, are permitted provided that the 
/// * following conditions are met: 

/// $ 

/// * - Redistributions of source code must retain the above 
117 $ copyright notice, this list of conditions and the 

/// + following disclaimer. 

111 $ 

/// # - Redistributions in binary form must reproduce the above 
117 $ copyright notice, this list of conditions and the 

117 8 following disclaimer in the documentation and/or other 
/// + materials provided with the distribution. 

111 $ 

/// $ - Neither the name of Internet Society, IETF or IETF 

111 # Trust, nor the names of specific contributors, may be 
/// # used to endorse or promote products derived from this 
/// $ software without specific prior written permission. 
/// $ 

/// $ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 

/// $ AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED 
/// $ WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 

/// $ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 

/// $ FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO 

/// $ EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 

/// $ LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
/// $ EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
117 $ NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 

/// $ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
/// $ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 

117 $ LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 

/// $ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
117 $ IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 
/// $ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

111 # 


<CODE ENDS> 
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4.2. 


Le 


LDAP Attributes 


The following definitions are used in this document: 


o 


o 


The name attribute described in [RFC4519]. 


The Integer syntax (1.3.6.1.4.1.1466.115.121.1.27) described in 
[RFC4517]. 


The integerMatch rule described in [RFC4517]. 


The Octet String syntax (1.3.6.1.4.1.1466.115.121.1.40) described 
in [RFC4517]. 


The octetStringMatch rule described in [RFC4517]. 


The Boolean syntax (1.3.6.1.4.1.1466.115.121.1.7) described in 
[RFC4517]. 


The booleanMatch rule described in [RFC4517]. 
The distinguishedNameMatch rule described in [RFC4517]. 


The DN syntax (1.3.6.1.4.1.1466.115.121.1.12) described in 
[RFC4517]. 


The labeledURI attribute described in [RFC2079]. 
The UUID syntax (1.3.6.1.1.16.1) described in [RFC4530]. 
The UuidMatch rule described in [RFC4530]. 


The UuidOrderingMatch rule described in [RFC4530]. 
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4.2.1.1.  fedfsUuid 


A fedfsUuid is the base type for all of the universally unique 
identifiers (UUIDs) used by the federated file system protocols. 


The fedfsUuid type is based on rules and syntax defined in [RFC4530]. 
A fedfsUuid is a single-valued LDAP attribute. 


«CODE BEGINS» 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.1 NAME 'fedfsUuid' 
/// DESC 'A UUID used by NSDB’ 

/// EQUALITY uuidMatch 

/// ORDERING uuidOrderingMatch 

11/ SYNTAX 1.3.6.1.1.16.1 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 
4.2.1.2. fedfsFsnUuid 


A fedfsFsnUuid represents the UUID component of an FSN. An NSDB 
SHOULD ensure that no two FSNs it stores have the same fedfsFsnUuid. 


This attribute is single-valued. 


<CODE BEGINS> 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.4 NAME ’ fedfsFsnUuid’ 
/// DESC 'The FSN UUID component of an FSN’ 
/// SUP fedfsUuid 

/// SINGLE-VALUE 

/// ) 

/// 


«CODE ENDS» 
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4.2.1.3. fedfsFsnTTL 


A fedfsFsnTTL is the time-to-live in seconds of a cached FSN and its 
child FSL records. It corresponds to the FsnTTL as defined in 
Section 2.7. See also Section 2.8.3 for information about caching 
FSLs. A fedfsFsnTTL MUST be encoded as an Integer syntax value 
[RFC4517] in the range [0, 4294967295]. 


This attribute is single-valued. 


«CODE BEGINS» 


11/ 

/// attributetype ( 

11/ 1.3.6.1.4.1.31103.1.11 NAME 'fedfsFsnTTL' 
/// DESC 'Time to live of an FSN tree’ 

/// EQUALITY integerMatch 

11/ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 

OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 
4.2.1.4.  fedfsNceDN 

A fedfsNceDN stores a distinguished name (DN). 

This attribute is single-valued. 


<CODE BEGINS> 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.14 NAME 'fedfsNceDN' 
/// DESC 'NCE Distinguished Name’ 

/// EQUALITY distinguishedNameMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 


OID 1.3.6.1.4.1.1466.115.121.1.12 is the DN syntax [RFC4517]. 
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4.2.1.5. fedfsFslUuid 


A fedfsFslUuid represents the UUID of an FSL. An NSDB SHOULD ensure 
that no two FSLs it stores have the same fedfsFslUuid. 


This attribute is single-valued. 


«CODE BEGINS» 


ER 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.8 NAME 'fedfsFslUuid" 
/// DESC 'UUID of an FSL’ 

/// SUP fedfsUuid 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 
4.2.1.6. fedfsAnnotation 


A fedfsAnnotation contains an object annotation formatted as a key/ 
value pair. 


This attribute is multi-valued; an object type that permits 
annotations may have any number of annotations per instance. 


A fedfsAnnotation attribute is a human-readable sequence of UTF-8 
characters with no non-terminal NUL characters. The value MUST be 
formatted according to the following ABNF [RFC5234] rules: 


ANNOTATION = KEY "=" VALUE 

KEY = ITEM 

VALUE = ITEM 

ITEM = *WSP DQUOTE UTF8-octets DQUOTE *WSP 


DQUOTE and WSP are defined in [RFC5234], and UTF8-octets is defined 
in [RFC3629]. 


The following escape sequences are allowed: 


AO do + 
| escape sequence | replacement | 
$ 55-55 - = R-—----------- + 
NN \ 
\ " " 
PoR ES ae do + 
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A fedfsAnnotation value might be processed as follows: 


1. Parse the attribute value according to the ANNOTATION rule, 
ignoring the escape sequences above. 


2. Scan through results of the previous step and replace the escape 
sequences above. 


A fedfsAnnotation attribute that does not adhere to this format 
SHOULD be ignored in its entirety. It MUST NOT prevent further 


processing of its containing entry. 


The following are examples of valid fedfsAnnotation attributes: 


"keyl" = "foo" 

"another key" = "x=3" 

"key-2" = "A string with \" and NN characters." 
" key3 "="bar" 


These correspond to the following key/value pairs: 


4------------- 4----------------------------------- + 
| key | value | 
4------------- 4----------------------------------- + 
| keyl | foo | 
| another key | x=3 | 
| key-2 | A string with " and Y characters. | 
| key3 | bar | 
4------------- HO + 
<CODE BEGINS> 

/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.12 NAME 'fedfsAnnotation' 

/// DESC 'Annotation of an object’ 

/// SUP name 

/// ) 

/// 


«CODE ENDS» 
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4.2.1.7. fedfsDescr 


A fedfsDescr stores an object description. The description MUST be 
encoded as a UTF-8 string. 


This attribute is multi-valued, which permits any number of 
descriptions per entry. 


«CODE BEGINS» 


117 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.13 NAME 'fedfsDescr' 
/// DESC 'Description of an object’ 

/// SUP name 

/// ) 

/// 


<CODE ENDS> 
4.2.1.8. fedfsNfsURI 


A fedfsNfsURI stores the host and pathname components of an FSL. A 
fedfsNfsURI MUST be encoded as an NFS URI (see Section 2.8.1). 


The fedfsNfsURI is a subtype of the labeledURI type [RFC2079], with 
the same encoding rules. 


This attribute is single-valued. 


<CODE BEGINS> 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.120 NAME ’ fedfsNfsURI’ 
/// DESC 'Location of fileset’ 

/// SUP labeledURI 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 
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4.2.1.9. fedfsNfsCurrency 


A fedfsNfsCurrency stores the NFSv4.1 fs locations server's 

fls currency value [RFC5661]. A fedfsNfsCurrency MUST be encoded as 
an Integer syntax value [RFC4517] in the range [-2147483648, 
2147483647]. 


This attribute is single-valued. 


<CODE BEGINS> 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.103 NAME 'fedfsNfsCurrency' 
/// DESC 'up-to-date measure of the data’ 

/// EQUALITY integerMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 

OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 
4.2.1.10. fedfsNfsGenFlagWritable 

A fedfsNfsGenFlagWritable stores the value of an FSL’s NFSv4.1 

FSLI4GF_WRITABLE bit [RFC5661]. A value of "TRUE" indicates the bit 


is set. A value of "FALSE" indicates the bit is not set. 


<CODE BEGINS> 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.104 NAME ' fedfsNfsGenFlagWritable’ 
/// DESC ’ Indicates if the file system is writable’ 

/// EQUALITY booleanMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 


OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517]. 
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4.2.1.11.  fedfsNfsGenFlagGoing 
A fedfsNfsGenFlagGoing stores the value of an FSL's NFSv4.1 
FSLIAGF GOING bit [RFC5661]. A value of "TRUE" indicates the bit is 
set. A value of "FALSE" indicates the bit is not set. 


«CODE BEGINS» 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.105 NAME ' fedfsNfsGenFlagGoing’ 
/// DESC 'Indicates if the file system is going’ 

/// EQUALITY booleanMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 


OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517]. 
4.2.1.12. fedfsNfsGenFlagSplit 

A fedfsNfsGenFlagSplit stores the value of an FSL’s NFSv4.1 

FSLI4GF_SPLIT bit [RFC5661]. A value of "TRUE" indicates the bit is 


set. A value of "FALSE" indicates the bit is not set. 


<CODE BEGINS> 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.106 NAME 'fedfsNfsGenFlagSplit' 
/// DESC 'Indicates if there are multiple file systems’ 
111 EQUALITY booleanMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 


OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517]. 
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4.2.1.13.  fedfsNfsTransFlagRdma 


A fedfsNfsTransFlagRdma stores the value of an FSL's NFSv4.1 
FSLIATF RDMA bit [RFC5661]. A value of "TRUE" indicates the bit is 
set. A value of "FALSE" indicates the bit is not set. 


«CODE BEGINS» 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.107 NAME 'fedfsNfsTransFlagRdma' 
/// DESC ‘Indicates if the transport supports RDMA' 

/// EQUALITY booleanMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 


OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517]. 


4.2.1.14. fedfsNfsClassSimul 


A fedfsNfsClassSimul contains the FSL’s NFSv4.1 FSLI4BX_CLSIMUL 
[RFC5661] value. A fedfsNfsClassSimul MUST be encoded as an Integer 
syntax value [RFC4517] in the range [0, 255]. 


<CODE BEGINS> 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.108 NAME 'fedfsNfsClassSimul' 
/// DESC 'The simultaneous-use class of the file system’ 
/// EQUALITY integerMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 


OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 
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4.2.1.15. fedfsNfsClassHandle 
A fedfsNfsClassHandle contains the FSL’s NFSv4.1 FSLIA4BX CLHANDLE 
[RFC5661] value. A fedfsNfsClassHandle MUST be encoded as an Integer 
syntax value [RFC4517] in the range [0, 255]. 


«CODE BEGINS» 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.109 NAME ’ fedfsNfsClassHandle’ 
/// DESC 'The handle class of the file system’ 

/// EQUALITY integerMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 

OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 
4.2.1.16. fedfsNfsClassFileid 

A fedfsNfsClassFileid contains the FSL’s NFSv4.1 FSLI4BX_CLFILEID 

[RFC5661] value. A fedfsNfsClassFileid MUST be encoded as an Integer 

syntax value [RFC4517] in the range [0, 255]. 


«CODE BEGINS» 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.110 NAME ’ fedfsNfsClassFileid’ 
/// DESC 'The fileid class of the file system’ 

/// EQUALITY integerMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 


OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 
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4.2.1.17.  fedfsNfsClassWritever 
A fedfsNfsClassWritever contains the FSL's NFSv4.1 FSLIABX CLWRITEVER 
[RFC5661] value. A fedfsNfsClassWritever MUST be encoded as an 
Integer syntax value [RFC4517] in the range [0, 255]. 


«CODE BEGINS» 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.111 NAME ’ fedfsNfsClassWritever’ 
/// DESC 'The write-verifier class of the file system’ 
/// EQUALITY integerMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 

OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 
4.2.1.18. fedfsNfsClassChange 

A fedfsNfsClassChange contains the FSL’s NFSv4.1 FSLI4BX_CLCHANGE 

[RFC5661] value. A fedfsNfsClassChange MUST be encoded as an Integer 

syntax value [RFC4517] in the range [0, 255]. 


<CODE BEGINS> 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.112 NAME ’ fedfsNfsClassChange’ 
/// DESC 'The change class of the file system’ 

/// EQUALITY integerMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 


OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 
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4.2.1.19. fedfsNfsClassReaddir 
A fedfsNfsClassReaddir contains the FSL's NFSv4.1 FSLIA4BX CLREADDIR 
[RFC5661] value. A fedfsNfsClassReaddir MUST be encoded as an 
Integer syntax value [RFC4517] in the range [0, 255]. 


«CODE BEGINS» 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.113 NAME 'fedfsNfsClassReaddir' 
/// DESC 'The readdir class of the file system’ 

/// EQUALITY integerMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 

OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 
4.2.1.20. fedfsNfsReadRank 

A fedfsNfsReadRank contains the FSL’s NFSv4.1 FSLI4BX_READRANK 

[RFC5661] value. A fedfsNfsReadRank MUST be encoded as an Integer 

syntax value [RFC4517] in the range [0, 255]. 


«CODE BEGINS» 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.114 NAME 'fedfsNfsReadRank' 
/// DESC 'The read rank of the file system’ 

/// EQUALITY integerMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 


OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 
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4.2.1.21. fedfsNfsReadOrder 


March 2015 


A fedfsNfsReadOrder contains the FSL's NFSv4.1 FSLIA4BX READORDER 
[RFC5661] value. A fedfsNfsReadOrder MUST be encoded as an Integer 


syntax value 
«CODE BEGINS 


/// 
/// 
/// 
/// 
/// 
/// 
/// 
/// 
/// 


<CODE ENDS> 


[RFC4517] in the range [0, 255]. 


> 


attributetype ( 
1.3.6.1.4.1.31103.1.115 NAME ’ fedfsNfsReadOrder’ 
DESC ‘The read order of the file system’ 
EQUALITY integerMatch 
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 
SINGLE-VALUE 
) 


OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 


4.2.1.22. fedf 


sNfsWriteRank 


A fedfsNfsWriteRank contains the FSL's FSLIA4BX WRITERANK [RFC5661] 
value. A fedfsNfsWriteRank MUST be encoded as an Integer syntax 


value [RFC45 
«CODE BEGINS 


/// 
/// 
/// 
/// 
/// 
/// 
/// 
/// 
/// 


<CODE ENDS> 


17] in the range [0, 255]. 


> 


attributetype ( 
1.3.6.1.4.1.31103.1.116 NAME ’ fedfsNfsWriteRank’ 
DESC ‘The write rank of the file system’ 
EQUALITY integerMatch 
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 
SINGLE-VALUE 
) 


OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 
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4.2.1.23. fedfsNfsWriteOrder 
A fedfsNfsWriteOrder contains the FSL's FSLI4BX_WRITEORDER [RFC5661] 
value. A fedfsNfsWriteOrder MUST be encoded as an Integer syntax 
value [RFC4517] in the range [0, 255]. 


«CODE BEGINS» 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.117 NAME 'fedfsNfsWriteOrder' 
/// DESC 'The write order of the file system’ 

/// EQUALITY integerMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 

OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 
4.2.1.24.  fedfsNfsVarSub 

A fedfsNfsVarSub stores the value of an FSL's NFSv4.1 FSLIAIF VAR SUB 

bit [RFC5661]. A value of "TRUE" indicates the bit is set. A value 


of "FALSE" indicates the bit is not set. 


«CODE BEGINS» 


/// 

/// attributetype ( 

/// 1.3.6.1.4.1.31103.1.118 NAME 'fedfsNfsVarSub' 

/// DESC ‘Indicates if variable substitution is present’ 
/// EQUALITY booleanMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 

/// SINGLE-VALUE 

/// ) 

/// 


<CODE ENDS> 


OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517]. 
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4.2.1.25. fedfsNfsValidFor 
A fedfsNfsValidFor stores an FSL's NFSv4.1 fs locations info 
fli valid for value [RFC5661]. A fedfsNfsValidFor MUST be encoded as 
an Integer syntax value [RFC4517] in the range [-2147483648, 
2147483647]. 


An FSL's parent's fedfsFsnTTL value and its fedfsNfsValidFor value 
MAY be different. 


This attribute is single-valued. 


«CODE BEGINS» 


11/ 

/// attributetype ( 

11/ 1.3.6.1.4.1.31103.1.19 NAME 'fedfsNfsValidFor' 
/// DESC 'Valid for time’ 

/// EQUALITY integerMatch 

/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 

/// SINGLE-VALUE 

/// ) 

/// 


OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 


<CODE ENDS> 
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4.2.2. LDAP Object Classes 

4.2.2.1.  fedfsNsdbContainerInfo 
A fedfsNsdbContainerInfo describes the location of the NCE. 
A fedfsNsdbContainerInfo's fedfsNceDN attribute is REQUIRED. 


A fedfsNsdbContainerInfo's fedfsAnnotation and fedfsDescr attributes 
are OPTIONAL. 


«CODE BEGINS» 


/// 

/// objectclass ( 

/// 1.3.6.1.4.1.31103.1.1001 NAME 'fedfsNsdbContainerInfo" 
/// DESC 'Describes NCE location’ 
/// SUP top AUXILIARY 

/// MUST ( 

/// fedfsNceDN 

/// ) 

/// MAY ( 

11/ fedfsAnnotation 

/// $ fedfsDescr 

/// )) 

11/ 


<CODE ENDS> 
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4.2.2.2.  fedfsFsn 
A fedfsFsn represents an FSN. 
A fedfsFsn's fedfsFsnUuid and fedfsFsnTTL attributes are REQUIRED. 
A fedfsFsn's fedfsAnnotation and fedfsDescr attributes are OPTIONAL. 
The DN of an FSN is REQUIRED to take the following form: 
"fedfsFsnUuid=$FSNUUID, $NCE", where SFSNUUID is the UUID of the FSN 
and $NCE is the DN of the NCE. Since LDAP requires a DN to be 
unique, this ensures that each FSN entry has a unique UUID value 


within the LDAP directory. 


«CODE BEGINS» 


/// 

/// objectclass ( 

/// 1.3.6.1.4.1.31103.1.1002 NAME ’ fedfsFsn’ 
/// DESC ’Represents a fileset’ 
/// SUP top STRUCTURAL 

/// MUST ( 

11/ fedfsFsnUuid 

/// $ fedfsFsnTTL 

/// ) 

/// MAY ( 

/// fedfsAnnotation 

/// $ fedfsDescr 

/// )) 

/// 


<CODE ENDS> 
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4.2.2.3.  fedfsFsl 
The fedfsFsl object class represents an FSL. 


The fedfsFsl is an abstract object class.  Protocol-specific subtypes 
of this object class are used to store FSL information. The 
fedfsNfsFsl object class defined in Section 4.2.2.4 is used to record 
an NFS FSL's location. Other subtypes MAY be defined for other 
protocols (e.g., Common Internet File System (CIFS)). 


A fedfsFsl's fedfsFslUuid and fedfsFsnUuid attributes are REQUIRED. 

A fedfsFsl's fedfsAnnotation and fedfsDescr attributes are OPTIONAL. 
The DN of an FSL is REQUIRED to take the following form: 
"fedfsFslUuid-$FSLUUID,fedfsFsnUuid-$FSNUUID,$NCE", where SFSLUUID is 
the FSL's UUID, SFSNUUID is the FSN's UUID, and $NCE is the DN of the 
NCE. Since LDAP requires a DN to be unique, this ensures that each 


FSL entry has a unique UUID value within the LDAP directory. 


«CODE BEGINS» 


/// 

/// objectclass ( 

/// 1.3.6.1.4.1.31103.1.1003 NAME 'fedfsFsl' 
11/ DESC 'A physical location of a fileset’ 
/// SUP top ABSTRACT 

/// MUST ( 

/// fedfsFslUuid 

/// $ fedfsFsnUuid 

/// ) 

/// MAY ( 

/ / / fedfsAnnotation 

/// $ fedfsDescr 

/// )) 

/// 


<CODE ENDS> 
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4,2:2.4. fedfsNfsFsl 


A fedfsNfsFsl is used to represent an NFS FSL. The fedfsNfsFsl 
inherits all of the attributes of the fedfsFsl and extends the 
fedfsFsl with information specific to the NFS protocol. 


The DN of an NFS FSL is REQUIRED to take the following form: 
"fedfsFslUuid=SFSLUUID, fedfsFsnUuid=SFSNUUID, SNCE", where SFSLUUID is 
the FSL's UUID, SFSNUUID is the FSN’s UUID, and $NCE is the DN of the 
NCE. Since LDAP requires a DN to be unique, this ensures that each 
NFS FSL entry has a unique UUID value within the LDAP directory. 


«CODE BEGINS» 


11/ 

/// objectclass ( 

/// 1.3.6.1.4.1.31103.1.1004 NAME 'fedfsNfsFsl' 
/// DESC 'An NFS location of a fileset’ 
/// SUP fedfsFsl STRUCTURAL 

/// MUST ( 

/// fedfsNfsURI 

/// $ fedfsNfsCurrency 

/// $ fedfsNfsGenFlagWritable 
/// $ fedfsNfsGenFlagGoing 
/// $ fedfsNfsGenFlagSplit 
/// $ fedfsNfsTransFlagRdma 
/// $ fedfsNfsClassSimul 

/// $ fedfsNfsClassHandle 

/// $ fedfsNfsClassFileid 

/// $ fedfsNfsClassWritever 
/// $ fedfsNfsClassChange 

/// $ fedfsNfsClassReaddir 

/ / / $ fedfsNfsReadRank 

/// $ fedfsNfsReadOrder 

11/ $ fedfsNfsWriteRank 

/// $ fedfsNfsWriteOrder 

/// $ fedfsNfsVarSub 

11/ $ fedfsNfsValidFor 

/// )) 

PEL 


<CODE ENDS> 
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5. 


NSDB Operations 


The operations defined by the protocol can be described as several 
sub-protocols that are used by entities within a federation to 
perform different roles. 


The first of these sub-protocols defines how the state of an NSDB 

node can be initialized and updated. The primary use of this sub- 
protocol is by an administrator to add, edit, or delete filesets, 

their properties, and their fileset locations. 


The second of these sub-protocols defines the queries that are sent 
to an NSDB node in order to perform resolution (or to find other 
information about the data stored within that NSDB node) and the 
responses returned by the NSDB node. The primary use of this sub- 
protocol is by a fileserver in order to perform resolution, but it 
may also be used by an administrator to query the state of the 
system. 


The first and second sub-protocols are defined as LDAP operations, 
using the schema defined in the previous section. If each NSDB node 
is a standard LDAP server, then, in theory, it is unnecessary to 
describe the LDAP operations in detail because the operations are 
ordinary LDAP operations to query and update records. However, we do 
not require that an NSDB node implement a complete LDAP service. 
Therefore, we define the minimum level of LDAP functionality required 
to implement an NSDB node. 


The NSDB sub-protocols are defined in Section 5.1 and Section 5.2. 
The descriptions of LDAP messages in these sections use the LDAP Data 


Interchange Format (LDIF) [RFC2849]. In order to differentiate 
constant and variable strings in the LDIF specifications, variables 
are prefixed by a $ character and use all uppercase characters. For 


example, a variable named FOO would be specified as $FOO. 


This document uses the term "NSDB client" to refer to an LDAP client 
that uses either of the NSDB sub-protocols. 


The third sub-protocol defines the queries and other requests that 
are sent to a fileserver in order to get information from it or to 
modify the state of the fileserver in a manner related to the 
federation protocols. The primary purpose of this protocol is for an 
administrator to create or delete a junction or discover related 
information about a particular fileserver. 


The third sub-protocol is defined as an Open Network Computing (ONC) 
Remote Procedure Call (RPC) protocol. The reason for using ONC RPC 
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instead of LDAP is that all fileservers support ONC RPC, but some do 
not support an LDAP directory server. 


The ONC RPC administration protocol is defined in [RFC7533]. 
5.1. NSDB Operations for Administrators 


The admin entity initiates and controls the commands to manage 
fileset and namespace information. The protocol used for 
communicating between the admin entity and each NSDB node MUST be the 
LDAPv3 [RFC4510] protocol. 


The names we assign to these operations are entirely for the purpose 
of exposition in this document and are not part of the LDAP dialogs. 


5.1.1. Create an FSN 


This operation creates a new FSN in the NSDB by adding a new fedfsFsn 
entry in the NSDB's LDAP directory. 


A fedfsFsn entry contains a fedfsFsnUuid. The administrator chooses 
the fedfsFsnUuid by the process described in Section 2.12. A 
fedfsFsn entry also contains a fedfsFsnTTL. The fedfsFsnTTL is 
chosen by the administrator as described in Section 2.8.3. 


5.1.1.1. LDAP Request 


This operation is implemented using the LDAP ADD request described by 
the LDIF below. 


dn: fedfsFsnUuid=$FSNUUID, $NCE 
changeType: add 

objectClass: fedfsFsn 
fedfsFsnUuid: SFSNUUID 
fedfsFsnTTL: STTL 


For example, if SFSNUUID is "e8c4761c-eb3b-4307-86fc-f702da197966", 
STTL is "300" seconds, and $NCE is "o-fedfs", the operation would be: 


dn: fedfsFsnUuid-e8c4761c-eb3b-4307-86fc-f702da197966,0-fedfs 
changeType: add 

objectClass: fedfsFsn 

fedfsFsnUuid: e8c4761c-eb3b-4307-86f£c-f702da197966 
fedfsFsnTTL: 300 
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5.1.2. Delete an FSN 


This operation deletes an FSN by removing a fedfsFsn entry in the 
NSDB's LDAP directory. 


If the FSN entry being deleted has child FSL entries, this function 
MUST return an error. This ensures that the NSDB will not contain 
any orphaned FSL entries. A compliant LDAP implementation will meet 
this requirement since Section 4.8 of [RFC4511] defines the LDAP 
delete operation to only be capable of removing leaf entries. 


Note that the FSN delete function removes the fileset only from a 
federation namespace (by removing the records for that FSN from the 
NSDB node that receives this request). The fileset and its data are 
not deleted. Any junction that has this FSN as its target may 
continue to point to this non-existent FSN. A dangling reference may 
be detected when a fileserver tries to resolve a junction that refers 
to the deleted FSN. 


5.1.2.1. LDAP Request 


This operation is implemented using the LDAP DELETE request described 
by the LDIF below. 


dn: fedfsFsnUuid=$FSNUUID, $NCE 
changeType: delete 


For example, if SFSNUUID is "e8c4761c-eb3b-4307-86fc-f702dal97966" 
and $NCE is "o-fedfs", the operation would be: 


dn: fedfsFsnUuid-e8c4761c-eb3b-4307-86fc-f702da197966,0-fedfs 
changeType: delete 


5.1.3. Create an FSL 


This operation creates a new FSL for the given FSN by adding a new 
fedfsFsl entry in the NSDB's LDAP directory. 


A fedfsFsl entry contains a fedfsFslUuid and fedfsFsnUuid. The 
administrator chooses the fedfsFslUuid. The process for choosing the 
fedfsFslUuid is described in Section 2.12. The fedfsFsnUuid is the 
UUID of the FSL's FSN. 


The administrator will also set additional attributes depending on 
the FSL type. 
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5.1.3.1. LDAP Request 


This operation is implemented using the LDAP ADD request described by 
the LDIF below (Note: the LDIF shows the creation of an NFS FSL.) 


dn: fedfsFslUuid=$FSLUUID, fedfsFsnUuid=$FSNUUID, $NCE 
changeType: add 

objectClass: fedfsNfsFsl 
fedfsFslUuid: SFSLUUID 

fedfsFsnUuid: $FSNUUID 

fedfsNfsURI: nfs://SHOST:$PORT//SPATH 
fedfsNfsCurrency: $CURRENCY 
fedfsNfsGenFlagWritable: SWRITABLE 
fedfsNfsGenFlagGoing: $GOING 
fedfsNfsGenFlagSplit: $SPLIT 
fedfsNfsTransFlagRdma: $RDMA 
fedfsNfsClassSimul: $CLASS SIMUL 
fedfsNfsClassHandle:$CLASS HANDLE 
fedfsNfsClassFileid:$CLASS FILEID 
fedfsNfsClassWritever:$CLASS WRITEVER 
fedfsNfsClassChange: $CLASS CHANGE 
fedfsNfsClassReaddir: $CLASS READDIR 
fedfsNfsReadRank: $READ RANK 
fedfsNfsReadOrder: $READ ORDER 
fedfsNfsWriteRank: $WRITE RANK 
fedfsNfsWriteOrder: S$WRITE ORDER 
fedfsNfsVarSub: $VAR SUB 
fedfsNfsValidFor: $TIME 
fedfsAnnotation: SANNOTATION 
fedfsDescr: SDESCR 


For example, if $FSNUUID is "e8c4761c-eb3b-4307-86fc-f702da197966", 
SFSLUUID is "ba89a802-41a9-44cf-8447-dda367590eb3", SHOST is 
"server.example.com", SPORT is "20049", SPATH is stored in the file 
"/tmp/fsl path", SCURRENCY is "0" (an up-to-date copy), the FSL is 
writable, but not going, split, or accessible via Remote Direct 
Memory Access (RDMA), the simultaneous-use class is "1", the handle 
class is "O", the fileid class is "1", the write-verifier class is 
"1", the change class is "1", the readdir class is "9", the read rank 
is "7", the read order is "8", the write rank is "5", the write order 
is "6", variable substitution is false, $TIME is "300" seconds, 
SANNOTATION is ""foo" = "bar"", SDESC is "This is a description.", 
and $NCE is "o=fedfs", the operation would be (for readability, the 
DN is split into two lines): 
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dn: fedfsFslUuid=ba892802-41a9-44cf-8447-dda367590eb3, 
fedfsFsnUuid-e8c4761c-eb3b-4307-86fc-f702da197966,0-fedfs 

changeType: add 

objectClass: fedfsNfsFsl 

fedfsFslUuid: ba891802-41a9-44cf-8447-dda367590eb3 
fedfsFsnUuid: e8c4761c-eb3b-4307-86f£c-f£702da197966 
fedfsNfsURI: nfs://server.example.com:20049//tmp/fsl path 
fedfsNfsCurrency: O0 

fedfsNfsGenFlagWritable: TRUE 

fedfsNfsGenFlagGoing: FALSE 

fedfsNfsGenFlagSplit: FALSE 

fedfsNfsTransFlagRdma: FALSE 

fedfsNfsClassSimul: 1 

fedfsNfsClassHandle: 0 

fedfsNfsClassFileid: 1 

fedfsNfsClassWritever: 1 

fedfsNfsClassChange: 1 

fedfsNfsClassReaddir: 9 

fedfsNfsReadRank: 7 

fedfsNfsReadOrder: 8 

fedfsNfsWriteRank: 5 

fedfsNfsWriteOrder: 6 

fedfsNfsVarSub: FALSE 

fedfsNfsValidFor: 300 

fedfsAnnotation: "foo" - "par" 

fedfsDescr: This is a description. 


Selecting fedfsNfsFsl Values 


The fedfsNfsFSl object class is used to describe NFSv4-accessible 


filesets. 


For the reasons described in Section 2.8.4, administrators 


SHOULD choose reasonable values for all LDAP attributes of an 
NFSv4-accessible fedfsNfsFsl even though some of these LDAP 
attributes are not explicitly contained in an NFSv4 fs locations 
attribute. 


When the administrator is unable to choose reasonable values for the 
LDAP attributes not explicitly contained in an NFSv4 fs locations 


attribute, 


Lentini, 


et al. 


the values in the following table are RECOMMENDED. 


Standards Track [Page 46] 


REC 7532 NSDB Protocol for Federated File Systems March 2015 


ta E HO $ O O + 
| LDAP attribute | LDAP | Notes | 
| | value | 
AZ HO $ O E + 
| fedfsNfsCurrency | negative | Indicates that the server 
| | value | does not know the currency | 
| | | (see Section 11.10.1 of | 
| | | [RFC5661]). | 
fedfsNfsGenFlagWritable FALSE | Leaving unset is not harmful | 
| | (see Section 11.10.1 of 
| | | [RFC5661]). | 
| fedfsNfsGenFlagGoing | FALSE | NFS client will detect a | 
| | | migration event if the FSL | 
| | | becomes unavailable. 
| fedfsNfsGenFlagSplit | TRUE | Safe to assume that the FSL | 
| is split. | 
| fedfsNfsTransFlagRdma TRUE NFS client will detect if 
| | | RDMA access is available. | 
| fedfsNfsClassSimul | o | 0 is treated as non-matching | 
| | | (see Section 11.10.1 of | 
| | | [RFC5661]). | 
fedfsNfsClassHandle 0 | See fedfsNfsClassSimul note. | 
| fedfsNfsClassFileid | 0 See fedfsNfsClassSimul note. 
| fedfsNfsClassWritever | 0 | See fedfsNfsClassSimul note. | 
| fedfsNfsClassChange | 0 | See fedfsNfsClassSimul note. | 
| fedfsNfsClassReaddir | o | See fedfsNfsClassSimul note. | 
| fedfsNfsReadRank |0 | Highest value ensures FSL 
will be tried. | 
| fedfsNfsReadOrder 0 See fedfsNfsReadRank note. 
| fedfsNfsWriteRank | 0 | See fedfsNfsReadRank note. 
| fedfsNfsWriteOrder | o | See fedfsNfsReadRank note. 
| fedfsNfsVarSub | FALSE | NFSv4 does not define | 
| | | variable substitution in | 
| paths. | 
| fedfsNfsValidFor | 0 Indicates no appropriate 
| | | refetch interval (see | 
| | | Section 11.10.2 of | 
| | | [RFC5661]). | 
phn $ SS SS RAS + 


5.1.4. Delete an FSL 


This operation deletes an FSL record. The admin requests the NSDB 
node storing the fedfsFsl to delete it from its database. This 
operation does not result in fileset data being deleted on any 
fileserver. 
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5.1.4.1. LDAP Request 


The admin sends an LDAP DELETE request to the NSDB node to remove the 
FSL. 


dn: fedfsFslUuid=$FSLUUID, fedfsFsnUuid=$FSNUUID, $NCE 
changeType: delete 


For example, if $FSNUUID is "e8c4761c-eb3b-4307-86fc-f702dal97966", 
SFSLUUID is "ba89a802-41a9-44cf-8447-dda367590eb3", and $NCE is 
"o-fedfs", the operation would be (for readability, the DN is split 
into two lines): 


dn: fedfsFslUuid=ba892802-41a9-44cf-8447-dda367590eb3, 
fedfsFsnUuid-e8c4761c-eb3b-4307-86fc-f702da197966,0-fedfs 
changeType: delete 


5.1.5. Update an FSL 


This operation updates the attributes of a given FSL. This command 
results in a change in the attributes of the fedfsFsl at the NSDB 
node maintaining this FSL. The values of the fedfsFslUuid and 
fedfsFsnUuid attributes MUST NOT change during an FSL update. 


5.1.5.1. LDAP Request 


The admin sends an LDAP MODIFY request to the NSDB node to update the 
FSL. 


dn: fedfsFslUuid=$FSLUUID, fedfsFsnUuid=$FSNUUID, $NCE 
changeType: modify 
replace: SATTRIBUTE-TYPE 


For example, if SFSNUUID is "e8c4761c-eb3b-4307-86fc-f702dal97966", 
SFSLUUID is "ba89a802-41a9-44cf-8447-dda367590eb3", $NCE is 
"o-fedfs", and the administrator wished to change the NFS read rank 
to 10, the operation would be (for readability, the DN is split into 
two lines): 


dn: fedfsFslUuid=ba892802-41a9-44cf-8447-dda367590eb3, 
fedfsFsnUuid-e8c4761c-eb3b-4307-86fc-f702da197966,0-fedfs 

changeType: modify 

replace: fedfsNfsReadClass 

fedfsNfsReadRank: 10 
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5.2. NSDB Operations for Fileservers 
5.2.1. NSDB Container Entry (NCE) Enumeration 


To find the NCEs for the NSDB nsdb.example.com, a fileserver would do 
the following: 


nce list = empty 
connect to the LDAP directory at nsdb.example.com 
for each namingContext value $BAR in the root DSE 
/* SBAR is a DN */ 
query for a fedfsNceDN value at S$BAR 
/* 
* The RFC 4516 LDAP URL for this search would be 


ldap://nsdb.example.com:389/$BAR?fedfsNCceDN?? 
(objectClass-fedfsNsdbContainerInfo) 


+ + z 


*/ 
if a fedfsNceDN value is found 
add the value to the nce list 


5.2.2. Lookup FSLs for an FSN 


Using an LDAP search, the fileserver can obtain all of the FSLs for a 
given FSN. The FSN's fedfsFsnUuid is used as the search key. The 
following examples use the LDAP Uniform Resource Identifier (URI) 
format defined in [RFC4516]. 


To obtain a list of all FSLs for SFSNUUID on the NSDB named 
SNSDBNAME, the following search can be used (for readability, the URI 
is split into two lines): 


for each $NCE in nce list 
ldap://S$NSDBNAME/fedfsFsnUuid-S$FSNUUID, $NCE??one? 
(objectClass-fedfsFsl) 


This search is for the children of the object with DN 
"fedfsFsnUuid=$FSNUUID, SNCE" with a filter for 
"objectClass-fedfsFsl". The scope value of "one" restricts the 
search to the entry's children (rather than the entire subtree below 
the entry), and the filter ensures that only FSL entries are 
returned. 


For example, if SNSDBNAME is "nsdb.example.com", SFSNUUID is 


"e8c4761c-eb3b-4307-86fc-£702da197966", and $NCE is "o-fedfs", the 
search would be (for readability, the URI is split into three lines): 
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ldap://nsdb.example.com/ 
fedfsFsnUuid-e8c4761c-eb3b-4307-86f£c-£702da197966,0-fedfs 
??one? (objectClass-fedfsFsl) 


The following search can be used to obtain only the NFS FSLs for 
SFSNUUID on the NSDB named $NSDBNAME (for readability, the URI is 
split into two lines): 


for each $NCE in nce list 
ldap: //SNSDBNAME/fedfsFsnUuid=$FSNUUID, $NCE??0ne? 
(objectClass-fedfsNfsFsl) 


This also searches for the children of the object with DN 
"fedfsFsnUuid=SFSNUUID, $NCE", but the filter for "objectClass = 
fedfsNfsFsl" restricts the results to only NFS FSLs. 


For example, if SNSDBNAME is nsdb.example.com, $FSNUUID is "e8c4761c- 
eb3b-4307-86fc-f702da197966", and $NCE is "o-fedfs", the search would 
be (for readability, the URI is split into three lines): 


ldap://nsdb.example.com/ 
fedfsFsnUuid-e8c4761c-eb3b-4307-86f£c-£702da197966,0-fedfs 
??one? (objectClass-fedfsNfsFsl) 


The fileserver will generate a referral based on the set of FSLs 
returned by these queries using the process described in 
Section 2.8.4. 


5.3. NSDB Operations and LDAP Referrals 


The LDAPv3 protocol defines an LDAP referral mechanism that allows an 
LDAP server to redirect an LDAP client.  LDAPv3 defines two types of 
LDAP referrals: the Referral type defined in Section 4.1.10 of 
[RFC4511] and the SearchResultReference type defined in Section 4.5.3 
of [RFC4511]. In both cases, the LDAP referral lists one or more 
URIS for services that can be used to complete the operation. In the 
remainder of this document, the term "LDAP referral" is used to 
indicate either of these types. 


If an NSDB operation results in an LDAP referral, the NSDB client MAY 
follow the LDAP referral. An NSDB client's decision to follow an 
LDAP referral is implementation and configuration dependent. For 
example, an NSDB client might be configured to follow only those LDAP 
referrals that were received over a secure channel or only those that 
target an NSDB that supports encrypted communication. If an NSDB 
client chooses to follow an LDAP referral, the NSDB client MUST 
process the LDAP referral and prevent looping as described in 

Section 4.1.10 of [RFC4511]. 
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6. Security Considerations 


Both the NFSv4 and LDAPv3 protocols provide security mechanisms. 
When used in conjunction with the federated file system protocols 
described in this document, the use of these mechanisms is 
RECOMMENDED. Specifically, the use of RPCSEC GSS [RFC2203], which is 
built on the Generic Security Service Application Program Interface 
(GSS-API) [RFC2743], is RECOMMENDED on all NFS connections between a 
file-access client and fileserver. The security considerations 
sections of the NFSv4.0 [RFC7530] and NFSv4.1 [RFC5661] 
Specifications contain special considerations for the handling of 
GETATTR operations for the fs locations and fs locations info 
attributes. 


NSDB nodes and NSDB clients MUST implement support for TLS [RFC5246], 
as described in [RFC4513]. For all LDAP connections established by 
the federated file system protocols, the use of TLS is RECOMMENDED. 


If an NSDB client chooses to follow an LDAP referral, the NSDB client 
SHOULD authenticate the LDAP referral's target NSDB using the target 
NSDB's credentials (not the credentials of the NSDB that generated 


the LDAP referral). The NSDB client SHOULD NOT follow an LDAP 
referral that targets an NSDB for which it does not know the NSDB's 
credentials. 


Within a federation, there are two types of components an attacker 
may compromise: a fileserver and an NSDB. 


If an attacker compromises a fileserver, the attacker can interfere 
with a file-access client's file system input/output (I/O) operations 
(e.g., by returning fictitious data in the response to a read 
request) or can fabricate a referral. The attacker's abilities are 
the same regardless of whether or not the federation protocols are in 
use. While the federation protocols do not give the attacker 
additional capabilities, they are additional targets for attack. The 
LDAP protocol described in Section 5.2 SHOULD be secured using the 
methods described above to defeat attacks on a fileserver via this 
channel. 


If an attacker compromises an NSDB, the attacker will be able to 
forge FSL information and thus poison the fileserver's referral 
information. Therefore, an NSDB should be as secure as the 
fileservers that query it. The LDAP operations described in 
Section 5 SHOULD be secured using the methods described above to 
defeat attacks on an NSDB via this channel. 
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7. 


7. 


7 


A fileserver binds anonymously when performing NSDB operations. 

Thus, the contents and distinguished names of FSN and FSL records are 
required to be readable by anyone who can bind anonymously to an NSDB 
service. Section 2.12 presents the security considerations in the 
choice of the type of UUID used in these records. 


It should be noted that the federation protocols do not directly 
provide access to file system data. The federation protocols only 
provide a mechanism for building a namespace. All data transfers 
occur between a file-access client and fileserver just as they would 
if the federation protocols were not in use. As a result, the 
federation protocols do not require new user authentication and 
authorization mechanisms or require a fileserver to act as a proxy 
for a client. 


IANA Considerations 
1. Registry for the fedfsAnnotation Key Namespace 


This document defines the fedfsAnnotation key in Section 4.2.1.6. 
The fedfsAnnotation key namespace is managed by IANA.  IANA has 
created and now maintains a new registry entitled "FedFS Annotation 
Keys". The location of this registry is under a new heading called 
"Federated File System (FedFS) Parameters". The URL address is 
«http://www.iana.org/assignments/fedfs-parameters». 


Future registrations are to be administered by IANA using the "First 
Come First Served" policy defined in [RFC5226]. Registration 
requests MUST include the key (a valid UTF-8 string of any length), a 
brief description of the key's purpose, and an email contact for the 
registration. For viewing, the registry should be sorted 
lexicographically by key. There are no initial assignments for this 
registry. 


.2. Registry for FedFS Object Identifiers 


Using the process described in [RFC2578], one of the authors was 
assigned the Internet Private Enterprise Numbers range 
1.3.6.1.4.1.31103.x. Within this range, the subrange 
1.3.6.1.4.1.31103.1.x is permanently dedicated for use by the 
federated file system protocols. Unassigned OIDs in this range MAY 
be used for Private Use or Experimental Use as defined in [RFC5226]. 
New permanent FedFS OID assignments MUST NOT be made using OIDs in 
this range. 
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IANA has created and now maintains a new registry entitled "FedFS 
Object Identifiers" for the purpose of recording the allocations of 
FedFS Object Identifiers (OIDs) specified by this document. No 
future allocations in this registry are allowed. 


The location of this registry is under the heading "Federated File 
System (FedFS) Parameters", created in Section 7.1. The URL address 
is <http://www.iana.org/assignments/fedfs-parameters>. 


For viewing, the registry has been sorted numerically by OID value. 
The contents of the "FedFS Object Identifiers" registry are given in 
Table 1. 


Note: A descriptor designated below as "historic" reserves an OID 
used in a past version of the NSDB protocol. Registering such OIDs 
retains compatibility among existing implementations of the NSDB 
protocol. This document does not otherwise refer to historic OIDs. 
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T ——————— ——Á—— a (TQ 
| OID 
+ HS A AN A e A A A REPE 
| 1.3.6.1.4.1.31103.1.1 
A dd Le STO ST oo 
| 2340.14 1.91103: 073 
(Ala dl 231003 pisa 
| 23.8145 1:82103.1.5 
| 1.3.6.1.4.1.31103.1.6 
1,356141. 51103,19 
Ear ee Assis 8 
| 1.3.6.1.4.1.31103.1.9 
Viral dd LOS, doo 
| Pe SO. dd 1:9 T1103; T TL 
| 3h 9 6x1 d b 3LTOS, 1712 
| 1.39.6.1.4.1.31103.1.13 
1.3.6.1.4.1.31103.1.14 
| 1.3.6.1.4.1.31103.1.15 
| 1.3.6.1.4.1.31103.1.100 
A SOS 101 
[Ed De SOS 02 
| LS se sae SOS 1.0109 
1.3.6.1.4.1.31103.1.104 
| ieas InAs 1311031105 
| 1.3.6.1.4.1.31103.1.106 
[Tebea D 0107 
| 159260.1.4 1.311031 108 
| 1.3.6.1.4.1.31103.1.109 
1.3.6.1.4.1.31103.1.110 
| 1.3.6.1.4.1.31103.1.111 
(A Lado E OLE 1 T2 
| 1.3.6.1.4.1.31103.1.113 
[ted Presb os ec 34 
| 1.3.6.1.4.1.31103.1.115 
1.3.6.1.4.1.31103.1.116 
| 51,876. 104, Ea 103. 10117 
| dS ecl d LOS. Li. EIS 
| 59:67:12, 1:31103. 1.119 
| 1.3.6.1.4.1.31103.1.120 
| 1333054 de 1:59: T03. D-19001 
1:3.6.1.4.1.31103.1.1002 
| 1.3.6.1.4.1.31103.1.1003 
| 1336. tds BIOS 1004 
+ SS A SS ti T mA ee ee ee 
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fedfsUuid 
fedfsNetAddr 
fedfsNetPort 
fedfsFsnUuid 
fedfsNsdbName 
fedfsNsdbPort 
fedfsNcePrefix 
fedfsFslUuid 
fedfsFslHost 
fedfsFslPort 
fedfsFslTTL 
fedfsAnnotation 
fedfsDescr 

fedfsNceDN 
fedfsFsnTTL 
fedfsNfsPath 
fedfsNfsMajorVer 
fedfsNfsMinorVer 
fedfsNfsCurrency 
fedfsNfsGenFlagWritable 
fedfsNfsGenFlagGoing 
fedfsNfsGenFlagSplit 
fedfsNfsTransFlagRdma 
fedfsNfsClassSimul 
fedfsNfsClassHandle 
fedfsNfsClassFileid 
fedfsNfsClassWritever 
fedfsNfsClassChange 
fedfsNfsClassReaddir 
fedfsNfsReadRank 
fedfsNfsReadOrder 
fedfsNfsWriteRank 
fedfsNfsWriteOrder 
fedfsNfsVarSub 
fedfsNfsValidFor 
fedfsNfsURI 
fedfsNsdbContainerInfo 
fedfsFsn 

fedfsFsl 

fedfsNfsFsl 


Table 1 
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7.3. LDAP Descriptor Registration 


In accordance with Sections 3.4 and 4 of [RFC4520], 
identifier descriptors defined in this document 
been registered via the Expert Review process. 


Subject: Request for LDAP Descriptor Registration 
Person & email address to contact for further information: 


"Author/Change 


Controller" 


Specification:  RFC 7532 


Author/Change Controller: IESG (iesg@ietf.org) 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 
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1:36.l-4.1:31T1103.L.-T 
name):  fedfsUuid 


type 


1.3:05L4:1:311031.2 
name):  fedfsNetAddr 
type (historic) 


Pes LOS LS 
name):  fedfsNetPort 
type (historic) 


1:36.101524.T7.31103.1.4 
name):  fedfsFsnUuid 


type 


1.370:1012:4.15.31103.1.5 
name):  fedfsNsdbName 
type (historic) 


1.37.6.1:4.1.:31103;:41.6 
name):  fedfsNsdbPort 
type (historic) 


Lidl LOS eT 
name):  fedfsNcePrefix 
type (historic) 


1.3.:6.1:4.1.31103.1.:8 
name):  fedfsFslUuid 


type 
1:326.1.42.1:31103.1.9 


name):  fedfsFslHost 
type (historic) 
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(listed below) have 
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Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 
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l235s605L.4.-1:31103.17.10 
name):  fedfsFslPort 
type (historic) 


1.345.6:L4.1.97103.1.1t 
name):  fedfsFslTTL 
type (historic) 


1.3.6.1.4.1.31103.1.12 
name):  fedfsAnnotation 


type 


1.3.6.1.4.1.31103.1.13 


name): fedfsDescr 

type 
1:3.05L.4:1:311095.1:44 

name):  fedfsNceDN 

type 


33-645. 43 LLO3 keds 
name):  fedfsFsnTTL 
type 


123336: 4 Ts 31103, 1 100 
name): fedfsNfsPath 
type (historic) 


1.376.01.42.1.31103.1-101 
name):  fedfsNfsMajorVer 
type (historic) 


1.3.:6.1:4.1.31103.1.102 
name): fedfsNfsMinorVer 


type (historic) 


L.3920.1.424.1.31103;:1:103 


name): fedfsNfsCurrency 
type 

1.3:.6.1.42.1:3T1103.1.104 
name): fedfsNfsGenFlagWritable 
type 


1:3:96.1.2.1:231103.1.105 
name):  fedfsNfsGenFlagGoing 
type 
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Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 


Object Identifier: 


Descriptor (short 
Usage: attribute 
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1.3.6.1.4.1.31103.1.106 


name): 
type 


1.35 
name): 
type 


1.3. 
name): 


type 


1.2335 
name): 
type 


135 
name): 
type 


PD 
name): 
type 


123% 
name): 
type 


1.35 
name): 
type 


1.35 
name): 
type 


1:35 
name): 
type 


1:35 
name): 
type 


13 
name): 
type 


fedfsNfsGenFlagSplit 


.1.4.1.31103.1.107 


fedfsNfsTransFlagRdma 


.1.4.1.31103.1.108 


fedfsNfsClassSimul 


é1225:1:31103.1.109 


fedfsNfsClassHandle 


slo4:1.31103.1.4110 


fedfsNfsClassFileid 


ses AE LLO TEL 


fedfsNfsClassWritever 


.1.4.1.31103.1.112 


fedfsNfsClassChange 


.1.4.1.31103.1.113 


fedfsNfsClassReaddir 


31.4.1.31103.;1.114 


fedfsNfsReadRank 


wd 45 1:531103;L:.115 


fedfsNfsReadOrder 


«1.4.1.31103.1.116 


fedfsNfsWriteRank 


z1.24.1231103.1.117 


fedfsNfsWriteOrder 
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Object Identifier: 1.3.6.1.4.1.31103.1.118 
Descriptor (short name):  fedfsNfsVarSub 
Usage: attribute type 

Object Identifier: 1.3.6.1.4.1.31103.1.119 
Descriptor (short name):  fedfsNfsValidFor 
Usage: attribute type 

Object Identifier: 1.3.6.1.4.1.31103.1.120 
Descriptor (short name):  fedfsNfsURI 

Usage: attribute type 

Object Identifier: 1.3.6.1.4.1.31103.1.1001 
Descriptor (short name):  fedfsNsdbContainerInfo 
Usage: object class 

Object Identifier: 1.3.6.1.4.1.31103.1.1002 
Descriptor (short name):  fedfsFsn 

Usage: object class 

Object Identifier: 1.3.6.1.4.1.31103.1.1003 
Descriptor (short name): fedfsFsl 

Usage: object class 

Object Identifier: 1.3.6.1.4.1.31103.1.1004 


Descriptor 
Usage: object class 


8. Glossary 


Administrator: 


(short name): 


fedfsNfsFsl 


A user with the necessary authority to initiate 


administrative tasks on one or more servers. 


March 2015 


Admin Entity: 


File-Access Client: 
(NAS) 


A server or agent that administers a collection of 
fileservers and persistently stores the namespace information. 


Standard off-the-shelf, 


standard file-access protocol. 


Federation: 
fileservers that use a common set of interfaces and protocols in 
order to provide to file-access clients a federated namespace 
accessible through a file system access protocol. 


Fileserver: 


A set of fileserver collections and singleton 


network-attached storage 
client software that communicates with fileservers using a 


A server that stores physical fileset data or refers 


file-access clients to other fileservers. A fileserver provides 


access to its shared file system data via a file-access protocol. 


Lentini, 
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Fileset: The abstraction of a set of files and the directory tree 
that contains them. A fileset is the fundamental unit of data 
management in the federation. 


Note that all files within a fileset are descendants of one 
directory and that filesets do not span file systems. 


File System: A self-contained unit of export for a fileserver and 
the mechanism used to implement filesets. The fileset does not 
need to be rooted at the root of the file system, nor at the 
export point for the file system. 


A single file system MAY implement more than one fileset, if the 
file-access protocol and the fileserver permit this. 


File-Access Protocol: A network file system access protocol such as 
NFSv3 [RFC1813], NFSv4 [RFC7530], or CIFS (Common Internet File 
System) [MS-SMB] [MS-SMB2] [MS-CIFS]. 


FSL (Fileset Location): The location of the implementation of a 
fileset at a particular moment in time. An FSL MUST be something 
that can be translated into a protocol-specific description of a 
resource that a file-access client can access directly, such as an 
fs locations attribute (for NFSv4) or a share name (for CIFS). 


FSN (Fileset Name): A platform-independent and globally unique name 
for a fileset. Two FSLs that implement replicas of the same 
fileset MUST have the same FSN, and if a fileset is migrated from 
one location to another, the FSN of that fileset MUST remain the 
same. 


Junction: A file system object used to link a directory name in the 
current fileset with an object within another fileset. The 
server-side "link" from a leaf node in one fileset to the root of 
another fileset. 


Namespace: A filename/directory tree that a sufficiently authorized 
file-access client can observe. 


NSDB (Namespace Database) Service: A service that maps FSNs to FSLs. 
The NSDB may also be used to store other information, such as 
annotations for these mappings and their components. 


NSDB Node: The name or location of a server that implements part of 
the NSDB service and is responsible for keeping track of the FSLs 
(and related information) that implement a given partition of the 
FSNs. 
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Referral: A server response to a file-access client access that 
directs the client to evaluate the current object as a reference 
to an object at a different location (specified by an FSL) in 
another fileset and possibly hosted on another fileserver. The 
client re-attempts the access to the object at the new location. 


Replica: A redundant implementation of a fileset. Each replica 
shares the same FSN but has a different FSL. 


Replicas may be used to increase availability or performance. 
Updates to replicas of the same fileset MUST appear to occur in 
the same order; therefore, each replica is self-consistent at any 
moment. 


We do not assume that updates to each replica occur 
simultaneously. If a replica is offline or unreachable, the other 
replicas may be updated. 


Server Collection: A set of fileservers administered as a unit. A 
server collection may be administered with vendor-specific 
software. 


The namespace provided by a server collection could be part of the 
federated namespace. 


Singleton Server: A server collection containing only one server; a 
stand-alone fileserver. 
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